\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename multiboot.info
@include version.texi
@settitle Multiboot2 Specification version @value{VERSION}
@c Unify all our little indices for now.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@c %**end of header

@footnotestyle separate
@paragraphindent 3
@finalout

@copying
Copyright @copyright{} 1995,96 Bryan Ford <baford@@cs.utah.edu>

Copyright @copyright{} 1995,96 Erich Stefan Boleyn <erich@@uruk.org>

Copyright @copyright{} 1999,2000,2001,2002,2005,2006,2009,2010,2016 Free Software Foundation, Inc.

@quotation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified
versions.
@end quotation
@end copying

@dircategory Kernel
@direntry
* Multiboot2 Specification: (Multiboot2).		Multiboot2 Specification.
@end direntry

@titlepage
@sp 10
@title The Multiboot2 Specification version @value{VERSION}
@author Yoshinori K. Okuji, Bryan Ford, Erich Stefan Boleyn,
@author Kunihiro Ishiguro, Vladimir 'phcoder' Serbinenko,
@author Daniel Kiper
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@finalout
@headings double

@ifnottex
@node Top
@top Multiboot2 Specification

This file documents Multiboot2 Specification, the proposal for the boot
sequence standard. This edition documents version @value{VERSION}.

@insertcopying
@end ifnottex

@menu
* Overview::                    
* Terminology::                 
* Specification::               
* Examples::                    
* History::                     
* Index::                       
@end menu


@node Overview
@chapter Introduction to Multiboot2 Specification

This chapter describes some rough information on the Multiboot2
Specification. Note that this is not a part of the specification itself.

@menu
* Motivation::                  
* Architecture::                
* Operating systems::           
* Boot sources::                
* Boot-time configuration::     
* Convenience to operating systems::  
* Boot modules::                
@end menu


@node Motivation
@section The background of Multiboot2 Specification

Every operating system ever created tends to have its own boot loader.
Installing a new operating system on a machine generally involves
installing a whole new set of boot mechanisms, each with completely
different install-time and boot-time user interfaces. Getting multiple
operating systems to coexist reliably on one machine through typical
@dfn{chaining} mechanisms can be a nightmare. There is little or no
choice of boot loaders for a particular operating system --- if the one
that comes with the operating system doesn't do exactly what you want,
or doesn't work on your machine, you're screwed.

While we may not be able to fix this problem in existing proprietary
operating systems, it shouldn't be too difficult for a few people in the
free operating system communities to put their heads together and solve
this problem for the popular free operating systems. That's what this
specification aims for. Basically, it specifies an interface between a
boot loader and a operating system, such that any complying boot loader
should be able to load any complying operating system. This
specification does @emph{not} specify how boot loaders should work ---
only how they must interface with the operating system being loaded.


@node Architecture
@section The target architecture

This specification is primarily targeted at @sc{pc}, since they are the
most common and have the largest variety of operating systems and boot
loaders. However, to the extent that certain other architectures may
need a boot specification and do not have one already, a variation of
this specification, stripped of the x86-specific details, could be
adopted for them as well.


@node Operating systems
@section The target operating systems

This specification is targeted toward free 32-bit operating systems
that can be fairly easily modified to support the specification without
going through lots of bureaucratic rigmarole. The particular free
operating systems that this specification is being primarily designed
for are Linux, the kernels of FreeBSD and NetBSD, Mach, and VSTa. It is hoped that other
emerging free operating systems will adopt it from the start, and thus
immediately be able to take advantage of existing boot loaders. It would
be nice if proprietary operating system vendors eventually adopted this
specification as well, but that's probably a pipe dream.


@node Boot sources
@section Boot sources

It should be possible to write compliant boot loaders that load the OS
image from a variety of sources, including floppy disk, hard disk, and
across a network.

Disk-based boot loaders may use a variety of techniques to find the
relevant OS image and boot module data on disk, such as by
interpretation of specific file systems (e.g. the BSD/Mach boot loader),
using precalculated @dfn{blocklists} (e.g. LILO), loading from a
special @dfn{boot partition} (e.g. OS/2), or even loading from within
another operating system (e.g. the VSTa boot code, which loads from
DOS). Similarly, network-based boot loaders could use a variety of
network hardware and protocols.

It is hoped that boot loaders will be created that support multiple
loading mechanisms, increasing their portability, robustness, and
user-friendliness.


@node Boot-time configuration
@section Configure an operating system at boot-time

It is often necessary for one reason or another for the user to be able
to provide some configuration information to an operating system
dynamically at boot time. While this specification should not dictate
how this configuration information is obtained by the boot loader, it
should provide a standard means for the boot loader to pass such
information to the operating system.


@node Convenience to operating systems
@section How to make OS development easier

OS images should be easy to generate. Ideally, an OS image should simply
be an ordinary 32-bit executable file in whatever file format the
operating system normally uses. It should be possible to @code{nm} or
disassemble OS images just like normal executables. Specialized tools
should not be required to create OS images in a @emph{special} file
format. If this means shifting some work from the operating system to
a boot loader, that is probably appropriate, because all the memory
consumed by the boot loader will typically be made available again after
the boot process is created, whereas every bit of code in the OS image
typically has to remain in memory forever. The operating system should
not have to worry about getting into 32-bit mode initially, because mode
switching code generally needs to be in the boot loader anyway in order
to load operating system data above the 1MB boundary, and forcing the
operating system to do this makes creation of OS images much more
difficult.

Unfortunately, there is a horrendous variety of executable file formats
even among free Unix-like @sc{pc}-based operating systems --- generally
a different format for each operating system. Most of the relevant free
operating systems use some variant of a.out format, but some are moving
to @sc{elf}. It is highly desirable for boot loaders not to have to be
able to interpret all the different types of executable file formats in
existence in order to load the OS image --- otherwise the boot loader
effectively becomes operating system specific again.

This specification adopts a compromise solution to this
problem. Multiboot2-compliant OS images always contain a magic
@dfn{Multiboot2 header} (@pxref{OS image format}), which allows the boot
loader to load the image without having to understand numerous a.out
variants or other executable formats. This magic header does not need to
be at the very beginning of the executable file, so kernel images can
still conform to the local a.out format variant in addition to being
Multiboot2-compliant.


@node Boot modules
@section Boot modules

Many modern operating system kernels, such as Mach and the microkernel in VSTa, do
not by themselves contain enough mechanism to get the system fully
operational: they require the presence of additional software modules at
boot time in order to access devices, mount file systems, etc. While
these additional modules could be embedded in the main OS image along
with the kernel itself, and the resulting image be split apart manually
by the operating system when it receives control, it is often more
flexible, more space-efficient, and more convenient to the operating
system and user if the boot loader can load these additional modules
independently in the first place.

Thus, this specification should provide a standard method for a boot
loader to indicate to the operating system what auxiliary boot modules
were loaded, and where they can be found. Boot loaders don't have to
support multiple boot modules, but they are strongly encouraged to,
because some operating systems will be unable to boot without them.


@node Terminology
@chapter The definitions of terms used through the specification

@table @dfn
@item must
We use the term @dfn{must}, when any boot loader or OS image needs to
follow a rule --- otherwise, the boot loader or OS image is @emph{not}
Multiboot2-compliant.

@item should
We use the term @dfn{should}, when any boot loader or OS image is
recommended to follow a rule, but it doesn't need to follow the rule.

@item may
We use the term @dfn{may}, when any boot loader or OS image is allowed
to follow a rule.

@item boot loader
Whatever program or set of programs loads the image of the final
operating system to be run on the machine. The boot loader may itself
consist of several stages, but that is an implementation detail not
relevant to this specification. Only the @emph{final} stage of the boot
loader --- the stage that eventually transfers control to an operating
system --- must follow the rules specified in this document in order
to be @dfn{Multiboot2-compliant}; earlier boot loader stages may be
designed in whatever way is most convenient.

@item OS image, kernel
The initial binary image that a boot loader loads into memory and
transfers control to start an operating system. The OS image is
typically an executable containing the operating system kernel.
However it doesn't need to be a part of any OS and may be any kind
of system tool.

@item boot module
Other auxiliary files that a boot loader loads into memory along with
an OS image, but does not interpret in any way other than passing their
locations to the operating system when it is invoked.

@item Multiboot2-compliant
A boot loader or an OS image which follows the rules defined as
@dfn{must} is Multiboot2-compliant. When this specification specifies a
rule as @dfn{should} or @dfn{may}, a Multiboot2-complaint boot loader/OS
image doesn't need to follow the rule.

@item u8
The type of unsigned 8-bit data.

@item u16
The type of unsigned 16-bit data. Because the target architecture is
little-endian, u16 is coded in little-endian.

@item u32
The type of unsigned 32-bit data. Because the target architecture is
little-endian, u32 is coded in little-endian.

@item u64
The type of unsigned 64-bit data. Because the target architecture is
little-endian, u64 is coded in little-endian.

@end table


@node Specification
@chapter The exact definitions of Multiboot2 Specification

There are three main aspects of a boot loader/OS image interface:

@enumerate
@item
The format of an OS image as seen by a boot loader.

@item
The state of a machine when a boot loader starts an operating
system.

@item
The format of information passed by a boot loader to an operating
system.
@end enumerate

@menu
* OS image format::             
* Machine state::               
* Boot information format::     
@end menu


@node OS image format
@section OS image format

An OS image may be an ordinary 32-bit executable file in the standard
format for that particular operating system, except that it may be
linked at a non-default load address to avoid loading on top of the
@sc{pc}'s I/O region or other reserved areas, and of course it should
not use shared libraries or other fancy features.

An OS image must contain an additional header called @dfn{Multiboot2
header}, besides the headers of the format used by the OS image. The
Multiboot2 header must be contained completely within the first 32768
bytes of the OS image, and must be 64-bit aligned. In
general, it should come @emph{as early as possible}, and may be
embedded in the beginning of the text segment after the @emph{real}
executable header.

@menu
* Header layout::               The layout of Multiboot2 header
* Header magic fields::         The magic fields of Multiboot2 header
* Header tags::
* Information request header tag::
* Address header tag::       
* Console header tags::
* Module alignment tag::
* EFI boot services tag::
* Relocatable header tag::

@end menu


@node Header layout
@subsection The layout of Multiboot2 header

The layout of the Multiboot2 header must be as follows:

@multitable @columnfractions .1 .1 .2 .5
@item Offset @tab Type  @tab Field Name   @tab Note
@item 0      @tab u32 @tab magic          @tab required
@item 4      @tab u32 @tab architecture   @tab required
@item 8      @tab u32 @tab header_length  @tab required
@item 12     @tab u32 @tab checksum       @tab required
@item 16-XX  @tab     @tab tags           @tab required
@end multitable

The fields @samp{magic}, @samp{architecture}, @samp{header_length} and @samp{checksum} are defined in @ref{Header magic fields}, @samp{tags}
are defined in @ref{Header tags}. All fields are in native endianness.
On bi-endian platforms native-endianness means the endiannes OS image starts in.


@node Header magic fields
@subsection The magic fields of Multiboot2 header

@table @samp
@item magic
The field @samp{magic} is the magic number identifying the header,
which must be the hexadecimal value @code{0xE85250D6}.

@item architecture
The field @samp{architecture} specifies the Central Processing Unit
Instruction Set Architecture. Since @samp{magic} isn't a palindrome
it already specifies the endianness ISAs differing only in endianness
recieve the same ID. @samp{0} means 32-bit (protected) mode of i386.
@samp{4} means 32-bit MIPS.

@item header_length
The field @samp{header_length} specifies the Length of Multiboot2 header
in bytes including magic fields.


@item checksum
The field @samp{checksum} is a 32-bit unsigned value which, when added
to the other magic fields (i.e. @samp{magic}, @samp{architecture} 
and @samp{header_length}), must have a 32-bit unsigned sum of zero.
@end table


@node Header tags
@subsection General tag structure
Tags constitutes a buffer of structures following each other padded when necessary
in order for each tag to start at 8-bytes aligned address. Tags are terminated by
a tag of type @samp{0} and size @samp{8}. Every structure has following format:

@example
@group
        +-------------------+
u16     | type              |
u16     | flags             |
u32     | size              |
        +-------------------+
@end group
@end example

@samp{type} is divided into 2 parts. Lower contains an identifier of contents of the rest of the tag.
@samp{size} contains the size of tag including header fields.
If bit @samp{0} of @samp{flags} (also known as @samp{optional}) is set, the bootloader may ignore this tag if it
lacks relevant support.
Tags are terminated by a tag of type @samp{0} and size @samp{8}.

@node Information request header tag
@subsection Multiboot2 information request

@example
@group
        +-------------------+
u16     | type = 1          |
u16     | flags             |
u32     | size              |
u32[n]  | mbi_tag_types     |
        +-------------------+
@end group
@end example

@samp{mbi_tag_types} is an array of u32's, each one representing an information request.

If this tag is present and @samp{optional} is set to @samp{0}, the bootloader must
support the requested tag and be able to provide relevant information to the image
if it is available. If the bootloader does not understand the meaning of the requested
tag it must fail with an error. However, if it supports a given tag but the information
conveyed by it is not available the bootloader does not provide the requested tag in
the Multiboot2 information structure and passes control to the loaded image as usual.

Note: The above means that there is no guarantee that any tags of type @samp{mbi_tag_types}
will actually be present. E.g. on a videoless system even if you requested tag @samp{8}
and the bootloader supports it, no tags of type @samp{8} will be present in the Multiboot2
information structure.


@node Address header tag
@subsection The address tag of Multiboot2 header

@example
@group
        +-------------------+
u16     | type = 2          |
u16     | flags             |
u32     | size              |
u32     | header_addr       |
u32     | load_addr         |
u32     | load_end_addr     |
u32     | bss_end_addr      |
        +-------------------+
@end group
@end example

All of the address fields in this tag are physical addresses.
The meaning of each is as follows:

@table @code
@item header_addr
Contains the address corresponding to the beginning of the Multiboot2
header --- the physical memory location at which the magic value is
supposed to be loaded. This field serves to @dfn{synchronize} the
mapping between OS image offsets and physical memory addresses.

@item load_addr
Contains the physical address of the beginning of the text segment. The
offset in the OS image file at which to start loading is defined by the
offset at which the header was found, minus (header_addr -
load_addr). load_addr must be less than or equal to header_addr.

Special value -1 means that the file must be loaded from its beginning.

@item load_end_addr
Contains the physical address of the end of the data
segment. (load_end_addr - load_addr) specifies how much data to load.
This implies that the text and data segments must be consecutive in the
OS image; this is true for existing a.out executable formats.
If this field is zero, the boot loader assumes that the text and data
segments occupy the whole OS image file.

@item bss_end_addr
Contains the physical address of the end of the bss segment. The boot
loader initializes this area to zero, and reserves the memory it
occupies to avoid placing boot modules and other data relevant to the
operating system in that area. If this field is zero, the boot loader
assumes that no bss segment is present.

@end table

Note: This information does not need to be provided if the kernel image
is in @sc{elf} format, but it must be provided if the image is in a.out
format or in some other format. When the address tag is present it must
be used in order to load the image, regardless of whether an @sc{elf}
header is also present. Compliant boot loaders must be able to load
images that are either in @sc{elf} format or contain the address tag
embedded in the Multiboot2 header.

@subsection The entry address tag of Multiboot2 header

@example
@group
        +-------------------+
u16     | type = 3          |
u16     | flags             |
u32     | size              |
u32     | entry_addr        |
        +-------------------+
@end group
@end example

All of the address fields in this tag are physical addresses.
The meaning of each is as follows:

@table @code

@item entry_addr
The physical address to which the boot loader should jump in order to
start running the operating system.
@end table

@subsection EFI i386 entry address tag of Multiboot2 header

@example
@group
        +-------------------+
u16     | type = 8          |
u16     | flags             |
u32     | size              |
u32     | entry_addr        |
        +-------------------+
@end group
@end example

All of the address fields in this tag are physical addresses.
The meaning of each is as follows:

@table @code

@item entry_addr
The physical address to which the boot loader should jump in order to
start running EFI i386 compatible operating system code.
@end table

This tag is taken into account only on EFI i386 platforms
when Multiboot2 image header contains EFI boot services tag.
Then entry point specified in ELF header and the entry address
tag of Multiboot2 header are ignored.

@subsection EFI amd64 entry address tag of Multiboot2 header

@example
@group
        +-------------------+
u16     | type = 9          |
u16     | flags             |
u32     | size              |
u32     | entry_addr        |
        +-------------------+
@end group
@end example

All of the address fields in this tag are physical addresses (paging
mode is enabled and any memory space defined by the UEFI memory map
is identity mapped, hence, virtual address equals physical address;
Unified Extensible Firmware Interface Specification, Version 2.6,
section 2.3.4, x64 Platforms, boot services). The meaning of each
is as follows:

@table @code

@item entry_addr
The physical address to which the boot loader should jump in order to
start running EFI amd64 compatible operating system code.
@end table

This tag is taken into account only on EFI amd64 platforms
when Multiboot2 image header contains EFI boot services tag.
Then entry point specified in ELF header and the entry address
tag of Multiboot2 header are ignored.

@node Console header tags
@subsection Flags tag

@example
@group
        +-------------------+
u16     | type = 4          |
u16     | flags             |
u32     | size = 12         |
u32     | console_flags     |
        +-------------------+
@end group
@end example

If this tag is present and bit 0 of @samp{console_flags} is set
at least one of supported consoles must be present and information about it must be available in mbi.
If bit @samp{1} of @samp{console_flags} is set it
indicates that the OS image has EGA text support.

@subsection The framebuffer tag of Multiboot2 header

@example
@group
        +-------------------+
u16     | type = 5          |
u16     | flags             |
u32     | size = 20         |
u32     | width             |
u32     | height            |
u32     | depth             |
        +-------------------+
@end group
@end example


This tag specifies the preferred graphics mode. If this tag is present
bootloader assumes that the payload has framebuffer support.
Note that that is only a @emph{recommended}
mode by the OS image. Boot loader may choose a different mode if it sees fit.

The meaning of each is as follows:

@table @code
@item width
Contains the number of the columns. This is specified in pixels in a
graphics mode, and in characters in a text mode. The value zero
indicates that the OS image has no preference.

@item height
Contains the number of the lines. This is specified in pixels in a
graphics mode, and in characters in a text mode. The value zero
indicates that the OS image has no preference.

@item depth
Contains the number of bits per pixel in a graphics mode, and zero in
a text mode. The value zero indicates that the OS image has no
preference.
@end table


@node Module alignment tag
@subsection Module alignment tag

@example
@group
        +-------------------+
u16     | type = 6          |
u16     | flags             |
u32     | size = 8          |
        +-------------------+
@end group
@end example

If this tag is present modules must be page aligned.

@node EFI boot services tag
@subsection EFI boot services tag

@example
@group
        +-------------------+
u16     | type = 7          |
u16     | flags             |
u32     | size = 8          |
        +-------------------+
@end group
@end example

This tag indicates that payload supports starting without
terminating boot services.

@node Relocatable header tag
@subsection Relocatable header tag

@example
@group
        +-------------------+
u16     | type = 10         |
u16     | flags             |
u32     | size = 24         |
u32     | min_addr          |
u32     | max_addr          |
u32     | align             |
u32     | preference        |
        +-------------------+
@end group
@end example

This tag indicates that image is relocatable.

The meaning of each field is as follows:

@table @code
@item min_addr
Lowest possible physical address at which image should be loaded.
The bootloader cannot load any part of image below this address.

@item max_addr
Highest possible physical address at which loaded image should end.
The bootloader cannot load any part of image above this address.

@item align
Image alignment in memory, e.g. 4096.

@item preference
It contains load address placement suggestion for boot loader.
Boot loader should follow it. @samp{0} means none, @samp{1} means
load image at lowest possible address but not lower than min_addr
and @samp{2} means load image at highest possible address but not
higher than max_addr.
@end table

@node Machine state
@section MIPS machine state

When the boot loader invokes the operating system, the machine
must have the following state:

@table @samp
@item R4 (also known as A0)
Must contain the magic value @samp{0x36d76289}; the presence of this
value indicates to the operating system that it was loaded by a
Multiboot2-compliant boot loader (e.g. as opposed to another type of
boot loader that the operating system can also be loaded from).

@item R5 (also known as A1)
Must contain the 32-bit physical address of the Multiboot2
information structure provided by the boot loader (@pxref{Boot
information format}).
@end table

All other processor registers and flag bits are undefined. This
includes, in particular:

@table @samp
@item R29/SP
The OS image must create its own stack as soon as it needs one.

@end table

@section I386 machine state

When the boot loader invokes the 32-bit operating system, the machine
must have the following state:

@table @samp
@item EAX
Must contain the magic value @samp{0x36d76289}; the presence of this
value indicates to the operating system that it was loaded by a
Multiboot2-compliant boot loader (e.g. as opposed to another type of
boot loader that the operating system can also be loaded from).

@item EBX
Must contain the 32-bit physical address of the Multiboot2
information structure provided by the boot loader (@pxref{Boot
information format}).

@item CS
Must be a 32-bit read/execute code segment with an offset of @samp{0}
and a limit of @samp{0xFFFFFFFF}. The exact value is undefined.

@item DS
@itemx ES
@itemx FS
@itemx GS
@itemx SS
Must be a 32-bit read/write data segment with an offset of @samp{0}
and a limit of @samp{0xFFFFFFFF}. The exact values are all undefined.

@item A20 gate
Must be enabled.

@item CR0
Bit 31 (PG) must be cleared. Bit 0 (PE) must be set. Other bits are
all undefined.

@item EFLAGS
Bit 17 (VM) must be cleared. Bit 9 (IF) must be cleared. Other bits
are all undefined.
@end table

All other processor registers and flag bits are undefined. This
includes, in particular:

@table @samp
@item ESP
The OS image must create its own stack as soon as it needs one.

@item GDTR
Even though the segment registers are set up as described above, the
@samp{GDTR} may be invalid, so the OS image must not load any segment
registers (even just reloading the same values!) until it sets up its
own @samp{GDT}.

@item IDTR
The OS image must leave interrupts disabled until it sets up its own
@code{IDT}.
@end table

On EFI system boot services must be terminated.

@section EFI i386 machine state with boot services enabled

When the boot loader invokes the 32-bit operating system on EFI i386
platform and EFI boot services tag together with EFI i386 entry address
tag are present in the image Multiboot2 header, the machine must have the
following state:

@table @samp
@item EAX
Must contain the magic value @samp{0x36d76289}; the presence of this
value indicates to the operating system that it was loaded by a
Multiboot2-compliant boot loader (e.g. as opposed to another type of
boot loader that the operating system can also be loaded from).

@item EBX
Must contain the 32-bit physical address of the Multiboot2
information structure provided by the boot loader (@pxref{Boot
information format}).
@end table

All other processor registers, flag bits and state are set accordingly
to Unified Extensible Firmware Interface Specification, Version 2.6,
section 2.3.2, IA-32 Platforms, boot services.

@section EFI amd64 machine state with boot services enabled

When the boot loader invokes the 64-bit operating system on EFI amd64
platform and EFI boot services tag together with EFI amd64 entry address
tag are present in the image Multiboot2 header, the machine must have the
following state:

@table @samp
@item EAX
Must contain the magic value @samp{0x36d76289}; the presence of this
value indicates to the operating system that it was loaded by a
Multiboot2-compliant boot loader (e.g. as opposed to another type of
boot loader that the operating system can also be loaded from).

@item EBX
Must contain the 64-bit physical address (paging mode is enabled and any
memory space defined by the UEFI memory map is identity mapped, hence,
virtual address equals physical address; Unified Extensible Firmware
Interface Specification, Version 2.6, section 2.3.4, x64 Platforms, boot
services) of the Multiboot2 information structure provided by the boot
loader (@pxref{Boot information format}).
@end table

All other processor registers, flag bits and state are set accordingly
to Unified Extensible Firmware Interface Specification, Version 2.6,
section 2.3.4, x64 Platforms, boot services.

The bootloader must not load any part of the kernel, the modules, the Multiboot2
information structure, etc. higher than 4 GiB - 1. This requirement is put in
force because most of currently specified tags supports 32-bit addresses only.
Additionally, some kernels, even if they run on EFI 64-bit platform, still
execute some parts of its initialization code in 32-bit mode.

Note: If at some point there is a need for full 64-bit mode support in Multiboot2
protocol then it should be designed very carefully. Especially it should be taken
into account that 32-bit and 64-bit mode code should coexist in an image without
any issue. The image should have a chance to inform the bootloader that it supports
full 64-bit mode. If it is the case then the bootloader should provide 64-bit tags
if it is desired and possible. Otherwise 32-bit tags should be used.

@node Boot information format
@section Boot information
@subsection Boot information format

Upon entry to the operating system, the @code{EBX} register contains the
physical address of a @dfn{Multiboot2 information} data structure,
through which the boot loader communicates vital information to the
operating system. The operating system can use or ignore any parts of
the structure as it chooses; all information passed by the boot loader
is advisory only.

The Multiboot2 information structure and its related substructures may be
placed anywhere in memory by the boot loader (with the exception of the
memory reserved for the kernel and boot modules, of course). It is the
operating system's responsibility to avoid overwriting this memory until
it is done using it.

@subsection Basic tags structure
Boot information consists of fixed part and a series of tags. Its start is 8-bytes aligned.  Fixed part is as following:
@example
@group
        +-------------------+
u32     | total_size        |
u32     | reserved          |
        +-------------------+
@end group
@end example

@samp{total_size} contains the total size of boot information including
this field and terminating tag in bytes

@samp{reserved} is always set to zero and must be ignored by OS image

Every tag begins with following fields:

@example
@group
        +-------------------+
u32     | type              |
u32     | size              |
        +-------------------+
@end group
@end example

@samp{type} contains an identifier of contents of the rest of the tag.
@samp{size} contains the size of tag including header fields but not including padding.
Tags follow one another padded when necessary in order for each tag to start at 8-bytes aligned address. Tags are terminated by a tag of type @samp{0} and size @samp{8}.

@subsection Basic memory information
@example
@group
        +-------------------+
u32     | type = 4          |
u32     | size = 16         |
u32     | mem_lower         |
u32     | mem_upper         |
        +-------------------+
@end group
@end example

 @samp{mem_lower} and @samp{mem_upper} indicate the amount of
lower and upper memory, respectively, in kilobytes. Lower memory starts
at address 0, and upper memory starts at address 1 megabyte. The maximum
possible value for lower memory is 640 kilobytes. The value returned for
upper memory is maximally the address of the first upper memory hole
minus 1 megabyte. It is not guaranteed to be this value.

This tag may not be provided by some boot loaders on EFI platforms if EFI boot
services are enabled and available for the loaded image (EFI boot services
not terminated tag exists in Multiboot2 information structure).

@subsection BIOS Boot device
@example
@group
        +-------------------+
u32     | type = 5          |
u32     | size = 20         |
u32     | biosdev           |
u32     | partition         |
u32     | sub_parition      |
        +-------------------+
@end group
@end example

This tag indicates which @sc{bios} disk device the boot
loader loaded the OS image from. If the OS image was not loaded from a
@sc{bios} disk, then this tag must not be present. The operating system may
use this field as a hint for determining its own @dfn{root} device,
but is not required to.

The @samp{biosdev} contains the @sc{bios} drive number as understood by the
@sc{bios} INT 0x13 low-level disk interface: e.g. 0x00 for the first
floppy disk or 0x80 for the first hard disk.

The three remaining bytes specify the boot partition. @samp{partition}
specifies the @dfn{top-level} partition number, @samp{sub_partition} specifies a
@dfn{sub-partition} in the top-level partition, etc. Partition numbers
always start from zero. Unused partition bytes must be set to 0xFFFFFFFF. For
example, if the disk is partitioned using a simple one-level DOS
partitioning scheme, then @samp{partition} contains the DOS partition
number, and @samp{sub_partition} if 0xFFFFFF. As another
example, if a disk is partitioned first into DOS partitions, and then
one of those DOS partitions is subdivided into several BSD partitions
using BSD's @dfn{disklabel} strategy, then @samp{partition} contains the DOS
partition number and @samp{sub_partition} contains the BSD sub-partition within
that DOS partition.

DOS extended partitions are indicated as partition numbers starting from
4 and increasing, rather than as nested sub-partitions, even though the
underlying disk layout of extended partitions is hierarchical in
nature. For example, if the boot loader boots from the second extended
partition on a disk partitioned in conventional DOS style, then
@samp{partition} will be 5, and @samp{sub_partiton} will be 0xFFFFFFFF.


@subsection Boot command line
@example
@group
        +-------------------+
u32     | type = 1          |
u32     | size              |
u8[n]   | string            |
        +-------------------+
@end group
@end example

@samp{string} contains command line. The command line is a normal C-style 
zero-terminated UTF-8 string.

@subsection Modules
@example
@group
        +-------------------+
u32     | type = 3          |
u32     | size              |
u32     | mod_start         |
u32     | mod_end           |
u8[n]   | string            |   
        +-------------------+
@end group
@end example

This tag indicates to the kernel what boot module was loaded along with the
kernel image, and where it can be found.

The @samp{mod_start} and @samp{mod_end} contain the start and end physical addresses
of the boot module itself. The @samp{string} field provides an arbitrary string to
be associated with that particular boot module; it is a zero-terminated
UTF-8 string, just like the kernel command line. Typically the
string might be a command line (e.g. if the operating system treats boot
modules as executable programs), or a pathname (e.g. if the operating
system treats boot modules as files in a file system), but its exact use
is specific to the operating system. 

One tag appears per module. This tag type may appear multiple times.

@subsection ELF-Symbols
@example
@group
        +-------------------+
u32     | type = 9          |
u32     | size              |
u16     | num               |
u16     | entsize           |
u16     | shndx             |
u16     | reserved          |
varies  | section headers   |
        +-------------------+
@end group
@end example

This tag contains section header table from an ELF kernel, the
size of each entry, number of entries, and the string table used as the
index of names. They correspond to the @samp{shdr_*} entries
(@samp{shdr_num}, etc.) in the Executable and Linkable Format (@sc{elf})
specification in the program header. All sections are loaded, and the
physical address fields of the @sc{elf} section header then refer to where
the sections are in memory (refer to the i386 @sc{elf} documentation for
details as to how to read the section header(s)).

@subsection Memory map

This tag provides memory map.

@example
@group
        +-------------------+
u32     | type = 6          |
u32     | size              |
u32     | entry_size        |
u32     | entry_version     |
varies  | entries           |
        +-------------------+
@end group
@end example

@samp{entry_size} contains the size of one entry so that in future new fields may be added to it. It's guaranteed to be a multiple of 8. @samp{entry_version} is currently set at @samp{0}. Future versions will increment this field. Future version are guranteed to be backward compatible with older format. Each entry has the following structure:


@example
@group
        +-------------------+
u64     | base_addr         |
u64     | length            |
u32     | type              |
u32     | reserved          |
        +-------------------+
@end group
@end example

@samp{size} contains the size of current entry including this field itself. It may be bigger than 24 bytes in future versions but is guaranteed to be
@samp{base_addr} is the starting physical address. @samp{length} is the size of the memory region in bytes.
@samp{type} is the variety of address range represented, where a
value of 1 indicates available @sc{ram}, value of 3 indicates usable memory
holding ACPI information, value of 4 indicates reserved memory which needs to
be preserved on hibernation, value of 5 indicates a memory which is occupied by defective RAM modules and all other values currently
indicated a reserved area.
@samp{reserved} is set to @samp{0} by bootloader and must be ignored by the OS image.

The map provided is guaranteed to list all standard @sc{ram} that should
be available for normal use. This type however includes the regions occupied by kernel, mbi, segments and modules. Kernel must take care not to overwrite these regions.

This tag may not be provided by some boot loaders on EFI platforms if EFI boot
services are enabled and available for the loaded image (EFI boot services
not terminated tag exists in Multiboot2 information structure).

@subsection Boot loader name
@example
@group
        +-------------------+
u32     | type = 2          |
u32     | size              |
u8[n]   | string            |
        +-------------------+
@end group
@end example

@samp{string} contains  the name of a boot
loader booting the kernel. The name is a normal C-style UTF-8 zero-terminated
string.

@subsection APM table
The tag type 10 contains @sc{apm} table
@example
@group
        +----------------------+
u32     | type = 10            |
u32     | size = 28            |
u16     | version              |
u16     | cseg                 |
u32     | offset               |
u16     | cseg_16              |
u16     | dseg                 |
u16     | flags                |
u16     | cseg_len             |
u16     | cseg_16_len          |
u16     | dseg_len             |
        +----------------------+
@end group
@end example

The fields @samp{version}, @samp{cseg}, @samp{offset}, @samp{cseg_16},
@samp{dseg}, @samp{flags}, @samp{cseg_len}, @samp{cseg_16_len},
@samp{dseg_len} indicate the version number, the protected mode 32-bit
code segment, the offset of the entry point, the protected mode 16-bit
code segment, the protected mode 16-bit data segment, the flags, the
length of the protected mode 32-bit code segment, the length of the
protected mode 16-bit code segment, and the length of the protected mode
16-bit data segment, respectively. Only the field @samp{offset} is 4
bytes, and the others are 2 bytes. See
@uref{http://www.microsoft.com/hwdev/busbios/amp_12.htm, Advanced Power
Management (APM) BIOS Interface Specification}, for more information.

@subsection VBE info
@example
@group
        +-------------------+
u32     | type = 7          |
u32     | size = 784        |
u16     | vbe_mode          |
u16     | vbe_interface_seg |
u16     | vbe_interface_off |
u16     | vbe_interface_len |
u8[512] | vbe_control_info  |
u8[256] | vbe_mode_info     |
        +-------------------+
@end group
@end example

The fields @samp{vbe_control_info} and @samp{vbe_mode_info} contain
@sc{vbe} control information returned by the
@sc{vbe} Function 00h and @sc{vbe} mode information returned by the
@sc{vbe} Function 01h, respectively.

The field @samp{vbe_mode} indicates current video mode in the format
specified in @sc{vbe} 3.0.

The rest fields @samp{vbe_interface_seg}, @samp{vbe_interface_off}, and
@samp{vbe_interface_len} contain the table of a protected mode interface
defined in @sc{vbe} 2.0+. If this information is not available, those
fields contain zero. Note that @sc{vbe} 3.0 defines another protected
mode interface which is incompatible with the old one. If you want to
use the new protected mode interface, you will have to find the table
yourself.

@subsection Framebuffer info
@example
@group
        +--------------------+
u32     | type = 8           |
u32     | size               |
u64     | framebuffer_addr   |
u32     | framebuffer_pitch  |
u32     | framebuffer_width  |
u32     | framebuffer_height |
u8      | framebuffer_bpp    |
u8      | framebuffer_type   |
u8      | reserved           |
varies  | color_info         |
        +--------------------+
@end group
@end example

The field @samp{framebuffer_addr} contains framebuffer physical address. This field is 64-bit wide but bootloader @dfn{should} set it under 4GiB if possible for compatibility with payloads which aren't aware of PAE or amd64. The field @samp{framebuffer_pitch} contains pitch in bytes. The fields @samp{framebuffer_width}, @samp{framebuffer_height} contain framebuffer dimensions in pixels. The field @samp{framebuffer_bpp} contains number of bits per pixel. @samp{reserved} always contains 0 in current version of specification and must be ignored by OS image. If @samp{framebuffer_type} is set to 0 it means indexed color. In this case color_info is defined as follows:
@example
@group
        +----------------------------------+
u32     | framebuffer_palette_num_colors   |
varies  | framebuffer_palette              |
        +----------------------------------+
@end group
@end example
@samp{framebuffer_palette} is an array of colour descriptors.
Each colour descriptor has following structure:
@example
@group
        +-------------+
u8      | red_value   |
u8      | green_value |
u8      | blue_value  |
        +-------------+
@end group
@end example
If @samp{framebuffer_type} is set to @samp{1} it means direct RGB color.
Then color_type is defined as follows:

@example
@group
       +----------------------------------+
u8     | framebuffer_red_field_position   |
u8     | framebuffer_red_mask_size        |
u8     | framebuffer_green_field_position |
u8     | framebuffer_green_mask_size      |
u8     | framebuffer_blue_field_position  |
u8     | framebuffer_blue_mask_size       |
       +----------------------------------+
@end group
@end example

If @samp{framebuffer_type} is set to @samp{2} it means EGA text. In this case @samp{framebuffer_width} and @samp{framebuffer_height} are expressed in characters and not in pixels. @samp{framebuffer_bpp} is equal 16 (16 bits per character) and @samp{framebuffer_pitch} is expressed in bytes per text line.
All further values of @samp{framebuffer_type} are reserved for future expansion

@subsection EFI 32-bit system table pointer
@example
@group
        +-------------------+
u32     | type = 11         |
u32     | size = 12         |
u32     | pointer           |
        +-------------------+
@end group
@end example

This tag contains pointer to i386 EFI system table.

@subsection EFI 64-bit system table pointer
@example
@group
        +-------------------+
u32     | type = 12         |
u32     | size = 16         |
u64     | pointer           |
        +-------------------+
@end group
@end example

This tag contains pointer to amd64 EFI system table.

@subsection SMBIOS tables
@example
@group
        +-------------------+
u32     | type = 13         |
u32     | size              |
u8      | major             |
u8      | minor             |
u8[6]   | reserved          |
        | smbios tables     |
        +-------------------+
@end group
@end example

This tag contains a copy of SMBIOS tables as well as their version.

@subsection ACPI old RSDP
@example
@group
        +-------------------+
u32     | type = 14         |
u32     | size              |
        | copy of RSDPv1    |
        +-------------------+
@end group
@end example

This tag contains a copy of RSDP as defined per ACPI 1.0 specification.

@subsection ACPI new RSDP
@example
@group
        +-------------------+
u32     | type = 15         |
u32     | size              |
        | copy of RSDPv2    |
        +-------------------+
@end group
@end example

This tag contains a copy of RSDP as defined per ACPI 2.0 or later specification.

@subsection Networking information
@example
@group
        +-------------------+
u32     | type = 16         |
u32     | size              |
        | DHCP ACK          |
        +-------------------+
@end group
@end example

This tag contains network information in the format specified as DHCP. It may be either a real DHCP reply or just the configuration info in the same format. This tag appears once per card.

@subsection EFI memory map
@example
@group
        +-------------------+
u32     | type = 17         |
u32     | size              |
u32     | descriptor size   |
u32     | descriptor version|
        | EFI memory map    |
        +-------------------+
@end group
@end example

This tag contains EFI memory map as per EFI specification.

This tag may not be provided by some boot loaders on EFI platforms if EFI boot
services are enabled and available for the loaded image (EFI boot services
not terminated tag exists in Multiboot2 information structure).

@subsection EFI boot services not terminated
@example
@group
        +-------------------+
u32     | type = 18         |
u32     | size = 8          |
        +-------------------+
@end group
@end example

This tag indicates ExitBootServices wasn't called

@subsection EFI 32-bit image handle pointer
@example
@group
        +-------------------+
u32     | type = 19         |
u32     | size = 12         |
u32     | pointer           |
        +-------------------+
@end group
@end example

This tag contains pointer to EFI i386 image handle.
Usually it is boot loader image handle.

@subsection EFI 64-bit image handle pointer
@example
@group
        +-------------------+
u32     | type = 20         |
u32     | size = 16         |
u64     | pointer           |
        +-------------------+
@end group
@end example

This tag contains pointer to EFI amd64 image handle.
Usually it is boot loader image handle.

@subsection Image load base physical address
@example
@group
        +-------------------+
u32     | type = 21         |
u32     | size = 12         |
u32     | load_base_addr    |
        +-------------------+
@end group
@end example

This tag contains image load base physical address. It is
provided only if image has relocatable header tag.

@node Examples
@chapter Examples

@strong{Caution:} The following items are not part of the specification
document, but are included for prospective operating system and boot
loader writers.

@menu
* C structure members alignment and padding consideration::
* Notes on PC::                 
* BIOS device mapping techniques::  
* Example OS code::             
* Example boot loader code::    
@end menu


@node C structure members alignment and padding consideration
@section C structure members alignment and padding consideration

It is preferred that the structures used for communication between the bootloader
and the OS image conform to chosen ABI for a given architecture. If it is not
possible then GCC @samp{__attribute__ ((__packed__))} (or anything else which has
similar meaning for chosen C compiler) have to be added to relevant structures
definitions to avoid spurious, in this case, padding and alignment.


@node Notes on PC
@section Notes on PC

In reference to bit 0 of the @samp{flags} parameter in the Multiboot2
information structure, if the bootloader in question uses older
@sc{bios} interfaces, or the newest ones are not available (see
description about bit 6), then a maximum of either 15 or 63 megabytes of
memory may be reported. It is @emph{highly} recommended that boot
loaders perform a thorough memory probe.

In reference to bit 1 of the @samp{flags} parameter in the Multiboot2
information structure, it is recognized that determination of which
@sc{bios} drive maps to which device driver in an operating system is
non-trivial, at best. Many kludges have been made to various operating
systems instead of solving this problem, most of them breaking under
many conditions. To encourage the use of general-purpose solutions to
this problem, there are 2 @sc{bios} device mapping techniques
(@pxref{BIOS device mapping techniques}). 

In reference to bit 6 of the @samp{flags} parameter in the Multiboot2
information structure, it is important to note that the data structure
used there (starting with @samp{BaseAddrLow}) is the data returned by
the INT 15h, AX=E820h --- Query System Address Map call. See @xref{Query
System Address Map, , Query System Address Map, grub.info, The GRUB
Manual}, for more information. The interface here is meant to allow a
boot loader to work unmodified with any reasonable extensions of the
@sc{bios} interface, passing along any extra data to be interpreted by
the operating system as desired.


@node BIOS device mapping techniques
@section BIOS device mapping techniques

Both of these techniques should be usable from any PC operating system,
and neither require any special support in the drivers themselves. This
section will be flushed out into detailed explanations, particularly for
the I/O restriction technique.

The general rule is that the data comparison technique is the quick and
dirty solution. It works most of the time, but doesn't cover all the
bases, and is relatively simple.

The I/O restriction technique is much more complex, but it has potential
to solve the problem under all conditions, plus allow access of the
remaining @sc{bios} devices when not all of them have operating system
drivers.

@menu
* Data comparison technique::   
* I/O restriction technique::   
@end menu


@node Data comparison technique
@subsection Data comparison technique

Before activating @emph{any} of the device drivers, gather enough data
from similar sectors on each of the disks such that each one can be
uniquely identified.

After activating the device drivers, compare data from the drives using
the operating system drivers. This should hopefully be sufficient to
provide such a mapping.

Problems:

@enumerate
@item
The data on some @sc{bios} devices might be identical (so the part
reading the drives from the @sc{bios} should have some mechanism to give
up).

@item
There might be extra drives not accessible from the @sc{bios} which are
identical to some drive used by the @sc{bios} (so it should be capable
of giving up there as well).
@end enumerate


@node I/O restriction technique
@subsection I/O restriction technique

This first step may be unnecessary, but first create copy-on-write
mappings for the device drivers writing into @sc{pc} @sc{ram}. Keep the
original copies for the @dfn{clean @sc{bios} virtual machine} to be
created later.

For each device driver brought online, determine which @sc{bios} devices
become inaccessible by:

@enumerate
@item
Create a @dfn{clean @sc{bios} virtual machine}.

@item
Set the I/O permission map for the I/O area claimed by the device driver
to no permissions (neither read nor write).

@item
Access each device.

@item
Record which devices succeed, and those which try to access the
@dfn{restricted} I/O areas (hopefully, this will be an @dfn{xor}
situation).
@end enumerate

For each device driver, given how many of the @sc{bios} devices were
subsumed by it (there should be no gaps in this list), it should be easy
to determine which devices on the controller these are.

In general, you have at most 2 disks from each controller given
@sc{bios} numbers, but they pretty much always count from the lowest
logically numbered devices on the controller.


@node Example OS code
@section Example OS code

In this distribution, the example Multiboot2 kernel @file{kernel} is
included. The kernel just prints out the Multiboot2 information structure
on the screen, so you can make use of the kernel to test a
Multiboot2-compliant boot loader and for reference to how to implement a
Multiboot2 kernel. The source files can be found under the directory
@file{doc} in the Multiboot2 source distribution.

The kernel @file{kernel} consists of only three files: @file{boot.S},
@file{kernel.c} and @file{multiboot2.h}. The assembly source
@file{boot.S} is written in GAS (@pxref{Top, , GNU assembler, as.info,
The GNU assembler}), and contains the Multiboot2 information structure to
comply with the specification. When a Multiboot2-compliant boot loader
loads and execute it, it initialize the stack pointer and @code{EFLAGS},
and then call the function @code{cmain} defined in @file{kernel.c}. If
@code{cmain} returns to the callee, then it shows a message to inform
the user of the halt state and stops forever until you push the reset
key. The file @file{kernel.c} contains the function @code{cmain},
which checks if the magic number passed by the boot loader is valid and
so on, and some functions to print messages on the screen. The file
@file{multiboot2.h} defines some macros, such as the magic number for the
Multiboot2 header, the Multiboot2 header structure and the Multiboot2
information structure.

@menu
* multiboot2.h::                 
* boot.S::                      
* kernel.c::                    
* Other Multiboot2 kernels::
@end menu


@node multiboot2.h
@subsection multiboot2.h

This is the source code in the file @file{multiboot2.h}:

@example
@include multiboot2.h.texi
@end example


@node boot.S
@subsection boot.S

In the file @file{boot.S}:

@example
@include boot.S.texi
@end example


@node kernel.c
@subsection kernel.c

And, in the file @file{kernel.c}:

@example
@include kernel.c.texi
@end example


@node Other Multiboot2 kernels
@subsection Other Multiboot2 kernels

Other useful information should be available in Multiboot2 kernels, such
as GNU Mach and Fiasco @url{http://os.inf.tu-dresden.de/fiasco/}. And,
it is worth mentioning the OSKit
@url{http://www.cs.utah.edu/projects/flux/oskit/}, which provides a
library supporting the specification.


@node Example boot loader code
@section Example boot loader code

The GNU GRUB (@pxref{Top, , GRUB, grub.info, The GRUB manual}) project
is a Multiboot2-compliant boot loader, supporting all required and
many optional features present in this specification. A public release has
not been made, but the test release is available from:

@url{ftp://alpha.gnu.org/gnu/grub}

See the webpage @url{http://www.gnu.org/software/grub/grub.html}, for
more information.


@node History
@chapter The change log of this specification

@table @asis
@item 0.7
@itemize @bullet
@item
@dfn{Multiboot2 Standard} is renamed to @dfn{Multiboot2 Specification}.

@item
Graphics fields are added to Multiboot2 header.

@item
BIOS drive information, BIOS configuration table, the name of a boot
loader, APM information, and graphics information are added to Multiboot2
information.

@item
Rewritten in Texinfo format.

@item
Rewritten, using more strict words.

@item
The maintainer changes to the GNU GRUB maintainer team
@email{bug-grub@@gnu.org}, from Bryan Ford and Erich Stefan Boleyn.

@item
The byte order of the @samp{boot_device} in Multiboot2 information is
reversed. This was a mistake.

@item
The offset of the address fields were wrong.

@item
The format is adapted to a newer Texinfo, and the version number is
specified more explicitly in the title.
@end itemize

@item 0.6
@itemize @bullet
@item
A few wording changes.

@item
Header checksum.

@item
Classification of machine state passed to an operating system.
@end itemize

@item 0.5
@itemize @bullet
@item
Name change.
@end itemize

@item 0.4
@itemize @bullet
@item
Major changes plus HTMLification.
@end itemize
@end table


@node Index
@unnumbered Index

@printindex cp

@contents
@bye
